How to Configure

ImageGear handles all of the memory mapped file operations internally, except for a specific case discussed in the next section. The application only needs to set a few parameters to enable the usage of memory mapped files and adjust it to its needs.

The usage of memory mapped files is controlled by three global control parameters:

"DIB.FILE_MAPPING.THRESHOLD". Specifies minimum DIB size, in megabytes, for which the memory mapped file shall be used. DIBs that are smaller than this threshold are allocated in physical memory. By default, this parameter is set to 0, which means that the use of memory mapped files is disabled. 1-bit images are always allocated in the physical memory and are not affected by this parameter.
"DIB.FILE_MAPPING.PATH". Specifies the path to a folder where memory mapped files will be stored. Memory mapped files are temporary files that are created upon DIB creation and deleted upon its deletion. By default, this parameter is set to an empty string, which means that ImageGear will use the system temporary folder for memory mapped files. This parameter is only used when the "DIB.FILE_MAPPING.THRESHOLD" parameter value is greater than zero. Does not affect 1-bit images.

For best performance, use a separate SSD drive or hard drive for storing memory mapped files, and make sure that the operating system and other applications do not use this drive.

"DIB.FILE_MAPPING.FLUSH_SIZE". Specifies the maximum size of a memory block in a DIB that can be processed without flushing the memory mapped file. The default value is 200 Mb, which shall be efficient on typical systems that have 4 Gb of RAM. Greater values may improve performance on systems that have a larger amount of RAM. However, making this value too big (comparable to RAM size) will impact the system responsiveness and may lead to allocation failure for large DIBs. This parameter is only used when the "DIB.FILE_MAPPING.THRESHOLD" parameter is greater than zero. Does not affect 1-bit images.

All three parameters DIB.FILE_MAPPING.THRESHOLD, DIB.FILE_MAPPING.PATH and DIB.FILE_MAPPING.FLUSH_SIZE are taken into account at the time of the DIB creation. After the DIB has been created, changing these parameters will not have an effect on the storage of this DIB, or flush frequency during its processing. However, if some operation replaces the DIB in a HIGEAR (e.g., Resize, Rotate), a new DIB will be created according to the current DIB.FILE_MAPPING.THRESHOLD and DIB.FILE_MAPPING.PATH values, and will then be processed according to the DIB.FILE_MAPPING.FLUSH_SIZE value at the time of the DIB replacement.

The following example tells ImageGear to use memory mapped files for images whose pixel data size is equal to or greater than 500 MB:

	Copy Code
// Memory mapping will be used for DIBs with sizes equal to or greater than 500 Mb. AT_INT fileMappingThreshold = 500; IG_gctrl_item_set("DIB.FILE_MAPPING.THRESHOLD", AM_TID_INT, &fileMappingThreshold, sizeof(fileMappingThreshold), "");

Copy Code

// Memory mapping will be used for DIBs with sizes equal to or greater than 500 Mb.
AT_INT fileMappingThreshold = 500;
IG_gctrl_item_set("DIB.FILE_MAPPING.THRESHOLD", AM_TID_INT, &fileMappingThreshold, sizeof(fileMappingThreshold), "");

The following example obtains the current value of the DIB.FILE_MAPPING.THRESHOLD parameter:

	Copy Code
// Get memory mapping threshold AT_INT fileMappingThreshold; IG_gctrl_item_get("DIB.FILE_MAPPING.THRESHOLD", NULL, (LPVOID)&fileMappingThreshold, sizeof(fileMappingThreshold), NULL, NULL, 0, NULL);

The following example tells ImageGear to create temporary memory-mapped files in the current directory:

	Copy Code
// Use current directory for the memory mapped files char* szMemoryMappingPath = "."; IG_gctrl_item_set("DIB.FILE_MAPPING.PATH", AM_TID_MAKELP(AM_TID_CHAR), szMemoryMappingPath, (DWORD)strlen(szMemoryMappingPath) + 1, "");

Copy Code

// Use current directory for the memory mapped files
char* szMemoryMappingPath = ".";
IG_gctrl_item_set("DIB.FILE_MAPPING.PATH", AM_TID_MAKELP(AM_TID_CHAR), szMemoryMappingPath, (DWORD)strlen(szMemoryMappingPath) + 1, "");

The following example obtains the directory used for storing memory mapped files:

	Copy Code
// Get path for memory mapped files char szMemoryMappingPath[_MAX_PATH]; IG_gctrl_item_get("DIB.FILE_MAPPING.PATH", NULL, (LPVOID)&szMemoryMappingPath, sizeof(szMemoryMappingPath) - 1, NULL, NULL, 0, NULL);

Copy Code

// Get path for memory mapped files
char szMemoryMappingPath[_MAX_PATH];
IG_gctrl_item_get("DIB.FILE_MAPPING.PATH", NULL, (LPVOID)&szMemoryMappingPath, sizeof(szMemoryMappingPath) - 1, NULL, NULL, 0, NULL);

The following example tells ImageGear to set the flush size to 100 Mb:

	Copy Code
// Memory mapping flush size will be equal to 200 Mb. AT_INT fileMappingFlushSize = 200; IG_gctrl_item_set("DIB.FILE_MAPPING.FLUSH_SIZE", AM_TID_INT, &fileMappingFlushSize, sizeof(fileMappingFlushSize), "");

Copy Code

// Memory mapping flush size will be equal to 200 Mb.
AT_INT fileMappingFlushSize = 200;
IG_gctrl_item_set("DIB.FILE_MAPPING.FLUSH_SIZE", AM_TID_INT, &fileMappingFlushSize, sizeof(fileMappingFlushSize), "");

The following example obtains the current flush size:

	Copy Code
// Get memory mapping flush size AT_INT fileMappingFlushSize; IG_gctrl_item_get("DIB.FILE_MAPPING.FLUSH_SIZE", NULL, (LPVOID)&fileMappingFlushSize, sizeof(fileMappingFlushSize), NULL, NULL, 0, NULL);